---
title: 配置概览
description: 了解配置和自定义新项目以及你的开发体验的方法。
i18nReady: true
---
import ReadMore from '~/components/ReadMore.astro'

Astro 是一个灵活、自由的框架，它允许你以多种不同的方式来配置你的项目。这意味着开始一个新项目可能会让人感到不知所措：因为没有“一个最好的方法”来设置你的 Astro 项目！

这个“配置”部分中的指南将帮助你熟悉各种文件，这些文件允许你配置和自定义项目和开发环境的各个方面。

如果这是你的第一个 Astro 项目，或者你已经有一段时间没有建立新项目了，请使用以下指南和文档中的参考来获取帮助。

可以通过在你的项目中添加一个 `astro.config.mjs` 文件来自定义 Astro 的运行方式。它是 Astro 项目中的常见文件，所有官方的示例模板和主题都默认包含该文件。

<ReadMore>阅读 Astro [API 的配置参考](/zh-cn/reference/configuration-reference/)以概览所有支持的配置项。</ReadMore>

## Astro 配置文件

[Astro 配置文件](/zh-cn/reference/configuration-reference/) 是一个 JavaScript 文件，它被包含在每个起始项目的根目录中：

```js
// astro.config.mjs
import { defineConfig } from "astro/config";

export default defineConfig({
  // 你的配置项都在这里
});
```

仅当你需要配置某些内容时才需要此文件，但大多数项目都会使用此文件。 `defineConfig()` 助手函数在你的 IDE 中提供自动化的 IntelliSense，你可以在其中添加所有配置选项，以告诉 Astro 如何构建项目并将其渲染为 HTML。

我们建议在大多数情况下使用默认文件格式 `.mjs`，如果你想在配置文件中编写 TypeScript，则使用 `.ts`。但是，也支持 `astro.config.js` 和 `astro.config.cjs`。

<ReadMore>阅读 Astro 的 [配置参考](/zh-cn/reference/configuration-reference/)，了解所有支持的配置选项的完整概述。</ReadMore>

## TypeScript 配置文件

每个 Astro 起始项目都包含了一个 `tsconfig.json` 文件。Astro 的[组件脚本](/zh-cn/basics/astro-components/#组件脚本)就是 Typescript，它提供 Astro 的编辑器工具，并允许你可选地向 JavaScript 添加语法，以对你自己的项目代码进行类型检查。

使用 `tsconfig.json` 文件配置 TypeScript 模板，该模板将对代码执行类型检查、配置 TypeScript 插件、设置导入别名等。

<ReadMore>阅读 Astro 的 [TypeScript 指南](/zh-cn/guides/typescript/)，了解 TypeScript 选项和 Astro 内置实用程序类型的完整概述。</ReadMore>

## 开发体验

当你处在开发模式下工作时，你可以利用代码编辑器和其他工具来改善 Astro 开发者的体验。

Astro 提供了自己的官方 VS Code 扩展，并且与其他几种流行的编辑器工具兼容。Astro 还提供了一个可自定义的工具栏，当开发服务器运行时，该工具栏会显示在浏览器预览中。你可以安装甚至构建自己的工具栏应用程序以获得附加功能。

<ReadMore>参阅 Astro 的[编辑器设置选项](/zh-cn/editor-setup/)和[使用开发工具栏](/zh-cn/guides/dev-toolbar/)指南，了解如何自定义你的开发体验。</ReadMore>

## 新项目常见事宜

以下是你在面对一个新的 Astro 项目时，可能会考虑的一些初始步骤。

### 添加你的部署域名

要生成站点地图并创建规范 URL，可以在 [`site`](/zh-cn/reference/configuration-reference/#site) 选项中配置部署 URL。如果你要部署到一个路径（例如 `www.example.com/docs`），你还可以为项目的根目录配置 [`base`](/zh-cn/reference/configuration-reference/#base)。

此外，部署时不同的 host 对于 URL 末尾的尾部斜杠可能有不同的行为。（例如 `example.com/about` 与 `example.com/about/`）。当部署站点后，你可能需要配置 [`trailingSlash`](/zh-cn/reference/configuration-reference/#trailingslash) 偏好。

```js title="astro.config.mjs"
import { defineConfig } from "astro/config";

export default defineConfig({
  site: "https://www.example.com",
  base: "/docs",
  trailingSlash: "always",
});
```

### 添加站点元数据

Astro 不会将其配置文件用于常见的 SEO 或元数据，它们仅用于构建项目代码并将其渲染为 HTML 所需的信息。

相反，这些信息会被渲染为标准的 HTML `<link>` 和 `<meta>` 标签添加到页面中的 `<head>` 中，就像编写纯 HTML 页面一样。

Astro 站点的一种常见做法是创建一个 `<Head />` [`.astro` 组件](/zh-cn/basics/astro-components/)，该组件可以添加到通用的[布局组件](/zh-cn/basics/layouts/)中，以便应用于你所有的页面。

```astro title="src/components/MainLayout.astro"
---
import Head from './Head.astro';

const { ...props } = Astro.props;
---
<html>
  <head>
    <meta charset="utf-8">
    <Head />
    <!-- head 部分的附加元素 -->
  </head>
  <body>
    <!-- 你的页面内容在这 -->
  </body>
</html>
```

因为 `Head.astro` 只是一个常规的 Astro 组件，所以你可以导入文件并接收从其他组件传递的 props，例如特定的页面标题。

```astro title="src/components/Head.astro"
---
import Favicon from '../assets/Favicon.astro';
import SomeOtherTags from './SomeOtherTags.astro';

const { title = 'My Astro Website', ...props } = Astro.props;
---
<link rel="sitemap" href="/sitemap-index.xml">
<title>{title}</title>
<meta name="description" content="Welcome to my new Astro site!">

<!-- 网站分析 -->
<script data-goatcounter="https://my-account.goatcounter.com/count" async src="//gc.zgo.at/count.js"></script>

<!-- 开放图谱标签 -->
<meta property="og:title" content="My New Astro Website" />
<meta property="og:type" content="website" />
<meta property="og:url" content="http://www.example.com/" />
<meta property="og:description" content="Welcome to my new Astro site!" />
<meta property="og:image" content="https://www.example.com/_astro/seo-banner.BZD7kegZ.webp">
<meta property="og:image:alt" content="">

<SomeOtherTags />

<Favicon />
```
